1 What is R Markdown?

R Markdown is a powerful tool that allows you to create dynamic documents that integrate code, text, and visualizations. R Markdown documents can be easily converted to various output formats (HTML, PDF, and more), which makes it versatile and practical. How does it work? You write text in Markdown, a simple markup language with an easy learning curve, and intertwine it with pieces of code whenever you feel like it, creating a unique workflow with lots of possibilities, from internal reports for your team to whole ready-to-publish documents that are fully reproducible.

A very common situation.
A very common situation.

In essence, R Markdown works as described in Figure 1.1. You write code and markdown text and create a .rmd document. When you are ready to generate the output, clicking on the Knit button (or using Shift + Ctrl + K on Windows, Command + Option + I on macOS) triggers a chain reaction that starts with the package knitr (Xie 2023b) (included in the rmarkdown package) converting the .rmd document into a pure markdown one or .md. Then pandoc, a free software document converter, is able to process the plain .md file and create your desired output whether it is a HTML, PDF, or Word document. However, these are not the only three possible outputs; with the help of other packages we can create multiple types of documents from presentations to websites.

R Markdown flow, from the `.rmd` file to the final output.

Figure 1.1: R Markdown flow, from the .rmd file to the final output.

At the end of this introduction to R Markdown we will have a look to several examples of the multiple outputs that we can generate with it. But, for now, let’s learn how to use it!

2 How do I use it?

In this section we will have a look at the practical information needed to leave this room knowing how to create and use your first R Markdown (.rmd) document.

2.1 My first .rmd document

Needless to say, the first step is to install R (R Core Team 2023)—you can find the newest update available here. It is also recommended but not strictly necessary to use the RStudio IDE, which you can download and install from here.

Next step is to install and load the package rmarkdown (Allaire et al. 2023):

install.packages("rmarkdown") # install the package
library(rmarkdown) # load the package

Now, for HTML output no extra action is needed, but if you need to create PDF you need to install LaTeX. You can do this using the package tinytex (Xie 2023c):

tinytex::install_tinytex()

After this, you can go to RStudio > File > New File > R Markdown, then choose the title for your document and output format between HTML (default), PDF and Word. All these specifications can be edited later.

2.2 .rmd file structure

2.2.1 YAML

YAML, that means YAML Ain’t Markup Language, is a human-readable serialization language that we can use at the beggining of an R Markdown document to specify the metadata and settings. It is automatically created when opening a new .rmd document from RStudio, but it can be manually created by indicating three dashes before and after like this:

---

YAML specifications

---

Here’s the YAML used to create this document:

---
title: "R Markdown for reproducible workflows"
subtitle: "**ecomeetings BC3**"
author: Rodrigo R. Granjel^[Basque Center for Climate Change (BC3); rodrigo.granjel@bc3research.org] and Francisco San Miguel, Oti^[Basque Center for Climate Change (BC3); francisco.sanmiguel@bc3research.org]
date: "March 7th, 2024"
output:
  html_document:
    toc: false
    toc_float: false
    theme: paper
    highlights: pygments
    number_sections: true
    df_print: paged
csl: settings/ecology-letters.csl
bibliography: references.bib
link-citations: yes
---

Notice that we have metadata such as author, title, or date, but also configuration options such as output format or reference styling. A full guide to the YAML parameters and configuration options is accessible here.

2.2.2 Formatted text

Very simple: this is simply just plain markdown text. We will learn how to use the basic formatting options in a minute.

2.2.3 Code

2.2.3.1 Code chunks

It’s like having mini (or not-so-mini) R scripts embedded in your text document, wherever you want to place them, but they’re now called chunks. They work independently but unidirectionally, meaning that a chunk can only use code outputs and refer to code chunks placed and ran before itself and not after. But, how do I create one of these chunks? To automatically create an R chunk, you can use the hotkey Alt + Ctrl + I on Windows or Command + Option + I on macOS. Else, you can manually create a chunk by enclosing your code in between two sets of three backticks: ```{r} chunk ```. Importantly, after the first three backticks you need to specify in brackets what language you want to use to run the code in the chunk; for R, the default option, it is {r}. This means that you can also add other programming languages to your workflow. A list of languages available can be found here.

It is also a good practice to name your chunk with a short label. To do this, you simply add the label next to the language determiner, such as this: {r label}. For example, if I’m using a chunk that runs the main simulation of my workflow, I can call it {r simulation}, or if I’m producing a figure such as a heat map, I can name the chunk {r heatmap_fig}. Very important: you cannot have repeated labels or the document won’t render!

Moreover, using a comma after the label allows you to access the configuration options for your chunk. For example, {r label, echo=FALSE} creates a chunk that hides the code but shows the results in a final output. This is great if you’re writing a paper, for example, and you want to place a figure in a particular spot of your document but not show the code behind it. Another examples are include, that determines whether both code and results show; message, for showing messages or not, as well as warning; or eval, to run or not the chunk but still show it. There are many other configuration options available and you can combine them as you desire. All options are described here.

If you don’t want to have to modify the chunk options every time you create a chunk, you can use a chunk at the beggining of your .rmd document to set the default options for all subsequent chunks, like this:

knitr::opts_chunk$set(echo=TRUE)

The wonderful thing about this is that you can always set specific instructions for a particular chunk and these will override the default options.

2.2.3.2 Inline code

This is my favorite thing of R Markdown (Rodrigo speaking). You can embed R code in between words to automatically generate the result of that line. Imagine you have the following sentence: “The value of the variable is 0.55, which is greater than 0.5.” However, you have to rerun your analyses with an additional set of data and now, the value of the variable has changed to 0.41 and no longer is greater than 0.5. You would have to rewrite the whole sentence—no big deal. But what if another collaborator in this global project sends you more data? Do you do it all again, and again, and again? R Markdown is here to lend you a hand.

# define the threshold
threshold <- 0.5

# select a random number for x (our variable)
x <- round(runif(1, 0, 1), 2)

The piece of code above defines a threshold (0.5 to follow the example) and then a random number between 0 and 1 that is assigned to x simulating a collaborator sending you new data and changing your results. Instead of panicking, we can automate the previous sentence like this:

The value of the variable is `r x`, which is `r if (x > threshold){paste("greater than")}else{if(x < threshold){paste("smaller than")}else{paste("equal to")}}` `r threshold`.

And it will automatically generate this sentence:

The value of the variable is 0.18, which is smaller than 0.5.

Basically, to add inline code you can use the backtick followed by the letter r, the code and a final backtick—as in the previous example.

2.3 Syntax

To nobody’s surprise, R Markdown uses the Markdown syntax. We will have a look at the basic commands (and some more advanced) commands that will allow us to create any document we desire.

2.3.1 Headers and lists

2.3.1.1 Line breaks and horizontal lines

For line breaks (change of paragraph):

  • two spaces at the end of the line
  • an html break: <br>
  • leaving a blank line
  • LaTex commands if you’re rendering a PDF

To include a horizontal line, you can use:

  • Three dashes on an otherwise blank line: ---
  • Three asterisks on an otherwise blank line: ***

If you use three dashes in between words it creates a long dash—just like that one.

2.3.1.2 Headers

Unlike in R code, where it begins a commentary, the pound sign followed by a space and text (# Text) defines a header:

  • # Header 1
  • ## Header 2
  • ### Header 3
  • #### Header 4
  • ##### Header 5

Interesting enough, these headers are not numbered by default, but you can add the command number_sections: true within the YAML to automatically number them, like this:

---
output:
  html_document:
    number_sections: true
---

Tip: do not skip a level when assigning numbered headers (e.g., by starting with ## Introduction instead of # Introduction), or else you’d get 0.1 Introduction instead of 1 Introduction.

2.3.1.3 Lists: bullets and numbers

For unordered lists, you can use *, - or +:

* First element  
- Second element
+ Third element

Generates the following list:

  • First element
  • Second element
  • Third element

Note that there must be a white line in between the list and the preceding text.

And then, for adding sublevels we simply indent the elements of the list:

- First element
  - Indented element
- Second element
- Third element
  - Sub-level one
    - Sub-level two

Makes:

  • First element
    • Indented element
  • Second element
  • Third element
    • Sub-level one
      • Sub-level two

And then, we can create numbered lists indicating numbers instead of bullets:

1. First element
7. Second element
3. Third element

Makes:

  1. First element
  2. Second element
  3. Third element

Notice that Markdown will automatically number the list in a consecutive manner, independently of the numbers you’ve used to create the list.

2.3.3 Emphasis, formulas and footnotes

2.3.3.1 Emphasis

One for italics:

  • *italics* gives italics
  • _italics_ gives italics

Two for bold:

  • **bold** gives bold
  • __bold__ gives bold

And use three to combine them:

  • ***bold italic*** gives bold italic
  • ___bold italic___ gives bold italic

2.3.3.2 Blockquotes

Using:

> *"Perhaps it’s impossible to wear an identity without becoming what you pretend to be."*--- Valentine Wiggin, 1985

Gives:

“Perhaps it’s impossible to wear an identity without becoming what you pretend to be.” — Valentine Wiggin, 1985

2.3.3.3 Equations

You can add equations using LaTeX. You can add them both inline: for example, the syntax $y = x + 1$ produces \(y = x + 1\) within the same line, but not referenced; or you can use the following syntax to create a referenced equation:

\begin{equation}
\bar{X} = \frac{\sum_{i=1}^n X_i}{n} (\#eq:mean)
\end{equation}
\[\begin{equation} \bar{X} = \frac{\sum_{i=1}^n X_i}{n} \tag{2.1} \end{equation}\]

2.3.3.4 Footnotes

This is also simple: use ^[footnote] to add a footnote, like this: ^[This is the footnote we were talking about!], which generates this3 (click on the superscript number go to the footnote at the very end of the document.) Note that Oti and I have also included our affiliation and email addresses as a footnote linked to our names at the very beggining of the document.

2.3.4 Cross-referencing

You can reference sections and code chunks within your same document. To do this, we need to create a label first. To set the label for the sections, you need to use {#label} next to the header of the section, like this: # Header {#label}. We explained how to label code chunks in Section 2.2.3. As an example: Section \@ref(usage) references Section 2 because that section was labeled this way: # How do I use it? {#usage}.

If you use the output bookdown::html_document2, you can cross-reference figures, tables and equations within the same document. For figures, for example, you need to write \ref@(fig:label-of-the-chunk-generating-the-figure). If we want to reference one of our figures, such as our amazing plot, you would do it like this: “Our amazing plot is in Figure \@ref(fig:cars)” produces “Our amazing plot is in Figure 2.1.”

You can find more information here.

2.3.5 Citations and bibliography

3 Examples

Examples of documents that can be generated with R Markdown:

This is a good place to look for examples.

Referencias

Aden-Buie, G., Sievert, C., Iannone, R., Allaire, J.J. & Borges, B. (2023). Flexdashboard: R markdown format for flexible dashboards.
Allaire, J.J., Xie, Y., Dervieux, C., McPherson, J., Luraschi, J., Ushey, K., et al. (2023). Rmarkdown: Dynamic documents for r.
Chang, W., Cheng, J., Allaire, J.J., Sievert, C., Schloerke, B., Xie, Y., et al. (2023). Shiny: Web application framework for r.
R Core Team. (2023). R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria.
Xie, Y. (2023a). Bookdown: Authoring books and technical documents with r markdown.
Xie, Y. (2023b). Knitr: A general-purpose package for dynamic report generation in r.
Xie, Y. (2023c). Tinytex: Helper functions to install and maintain TeX live, and compile LaTeX documents.
Xie, Y., Dervieux, C. & Hill, A.P. (2024). Blogdown: Create blogs and websites with r markdown.
Zhu, H. (2021). kableExtra: Construct complex table with ’kable’ and pipe syntax.

  1. Basque Center for Climate Change (BC3); ↩︎

  2. Basque Center for Climate Change (BC3); ↩︎

  3. This is the footnote we were talking about!↩︎